This PR addresses the common confusion where users install the onelogin package but try to import OneLogin_Saml2_Auth from onelogin.saml2.auth, which actually belongs to the separate python3-saml package. The solution now intelligently handles both scenarios: when python3-saml is not installed and when both packages are installed creating a namespace conflict.

Problem

Users were encountering a confusing ModuleNotFoundError: No module named 'onelogin.saml2' when trying to import:

from onelogin.saml2.auth import OneLogin_Saml2_Auth

The issue is more complex when users have both onelogin and python3-saml packages installed, creating a namespace conflict where the wrong package takes precedence.

Solution

Added an intelligent compatibility layer that:

1. Creates the missing module structure - Added onelogin/saml2/__init__.py and onelogin/saml2/auth.py
2. Detects python3-saml installation - Checks if python3-saml package is installed on the system
3. Provides context-aware error messages - Shows different guidance based on whether python3-saml is detected
4. Offers multiple resolution paths - Users can uninstall conflicting package, use virtual environments, or import directly from site-packages
5. Maintains backward compatibility - All existing functionality continues to work unchanged

Examples

When python3-saml is not installed:

from onelogin.saml2.auth import OneLogin_Saml2_Auth
# ImportError: OneLogin_Saml2_Auth is not available in this package.
# 
# This package (onelogin) is for OneLogin API management.
# For SAML2 authentication, you need the 'python3-saml' package.
# 
# To fix this:
# 1. Install the correct package: pip install python3-saml
# 2. Import from: from onelogin.saml2.auth import OneLogin_Saml2_Auth
# 
# For more information: https://github.com/onelogin/python3-saml

When python3-saml is installed (namespace conflict):

from onelogin.saml2.auth import OneLogin_Saml2_Auth
# ImportError: OneLogin_Saml2_Auth is not available due to a package namespace conflict.
# 
# You have both 'onelogin' (API management) and 'python3-saml' (SAML authentication) installed.
# These packages both provide 'onelogin' modules, causing a conflict.
# 
# To fix this conflict:
# 
# OPTION 1 - If you only need SAML authentication:
#   1. Uninstall this package: pip uninstall onelogin
#   2. Then import will work: from onelogin.saml2.auth import OneLogin_Saml2_Auth
# 
# OPTION 2 - If you need both packages:
#   1. Import directly from python3-saml's location in site-packages
#   2. See: https://github.com/onelogin/python3-saml for documentation
# 
# OPTION 3 - Use virtual environments to separate the packages
# 
# To check your installations: pip list | grep -E '(onelogin|python3-saml)'

Changes

• Added onelogin/saml2/__init__.py with module documentation
• Enhanced onelogin/saml2/auth.py with intelligent conflict detection and context-aware error messages
• Added comprehensive tests in test/test_saml2_import_compatibility.py covering both scenarios
• All existing tests continue to pass

This is a minimal, surgical change that only adds helpful guidance without modifying any existing functionality, now with intelligent detection to handle the most common user scenarios.

Fixes #103.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.